Before you begin the installation, make sure that you have reviewed the system requirements (see System Requirements), completed the prerequisites (see Planning & Preparing), and have your Keyfactor Command license file ready to upload during the configuration.
The following installation steps show all possible Keyfactor Command features enabled. Your Keyfactor Command license may not cover all Keyfactor Command features. If it does not, unlicensed features will not be shown in the configuration wizard. You may skip those configuration steps.
To begin the Keyfactor Command installation, execute the KeyfactorPlatform.msi file from the Keyfactor Command installation media and install as follows.
-
On the first installation page, click Next to begin the setup wizard.
Figure 534: Install: Begin Setup Wizard
- On the next page, read and accept the license agreement and click Next. Click Print to review a printed copy if desired.
-
On the next page, select the components to install. For a server with the default roles collocated, leave the default options and click Next to continue. If desired, you can highlight Keyfactor Command and click Browse to select an alternate installation location for the files. The default installation location is:
C:\Program Files\Keyfactor\Keyfactor Platform\Note: Although Figure 535: Install: Select Components shows only the default components selected, the remainder of this page covers configuring Keyfactor Command as though all the components have been selected.
Figure 535: Install: Select Components
Tip: Refer to Keyfactor Command Server(s) for a description of these components.Table 898: Available components for Keyfactor Command.
Component Description Management Portal Mandatory. Web-based management console for configuring all aspects of Keyfactor Command. The Keyfactor API will be installed with this component. Windows Services Mandatory. Includes the timer Windows service to manage timed events, such as CA Sync, PKI monitoring and system maintenance. Web API Optional. The Keyfactor API component. This allows the Keyfactor API for external use to be installed on a separate server from the Management Portal, if desired. Orchestrator Services API Optional. Only required if agents or orchestrators will be used in conjunction with Keyfactor Command. Web based orchestrator services API. CA Connector API Optional. Only required if remote CA clients will be used. Web based CA connector API. This component is disabled by default.
Important: This component requires an instance of RabbitMQ (https://www.rabbitmq.com) to complete the communication from Keyfactor Command to Remote CA Connectors and remote CAs (though RabbitMQ only communicates directly to Keyfactor Command, not the Remote CA Connectors). In many cases, this would be a containerized instance. For example:The component uses OAuth for authentication even if you've opted to use Active Directory authentication for the remainder of your Keyfactor Command installation, and therefore requires an OAuth 2.0 compliant implementation. You may choose to install Keyfactor Identity Provider if you do not have an alternate provider (see Installing Keyfactor Identity Provider).
- On the next screen, click Install.
- On the final installation wizard page, leave the Launch the Configuration Wizard now box selected and click Finish. The configuration wizard should start automatically. This can take several seconds.
-
On the Keyfactor Command Database Configuration page, enter the name, IP address, or fully qualified domain name (FQDN) of your SQL server and select a Credential Type of either Windows or SQL.
Important: Keyfactor Command uses an encrypted channel to connect to the SQL server by default, which requires configuration of an SSL
TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate on the SQL server (see Using SSL to Connect to SQL Server). The name or IP address you enter here for your SQL server must be available as a SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. in this certificate unless you have disabled the encrypted connection for Keyfactor Command (see Configurable SQL Connection Strings).-
If you select Windows as the Credential Type for connecting to SQL, click the Connect button.
Figure 536: Windows Authentication
-
If you select SQL as the Credential Type for connecting to SQL, the window will expand to include fields to enter a SQL username and password. Enter a username and password to authenticate to SQL, and click the Connect button.
Note: The password must not contain single or double quotes. An error will be shown if single or double quotes are used in the password.
Figure 537: SQL Authentication
Note: For the permissions required for this user, see Grant Permissions in SQL.Note: Keyfactor Command supports configuration of a base SQL connection template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. that is used for all connections Keyfactor Command makes to SQL. For more information, see Configurable SQL Connection Strings.Note: Your SQL server must be configured to support mixed mode authentication in order to use the SQL option. -
-
After the Connect button is clicked, the database name field will be activated. You can either enter the name of the desired database—for either a new or existing database—or click Browse to scroll through a list of existing databases.
Note: On subsequent runs of the configuration wizard, the database name field will be pre-populated with the database name used on the last completed run. Any change to the server connection fields (server name, authentication type, etc.) will require the Connect button to be used again to unlock the database name field and the Continue button. -
Click the Continue button. You will receive a confirmation dialog if any changes will be made to the database at this stage.
Note: If any of the following situations occurs, you will receive a message:- The selected database does not exist and will be created.
- The selected database is empty and not associated with Keyfactor Command; it will be populated with the Keyfactor Command schema.
- The selected database does not match the current product schema and will be upgraded.
- The selected database is not empty and is not associated with Keyfactor Command.
- The user does not have access to the database.
- An SSL certificate is not correctly configured on the SQL server.
-
On the Keyfactor Command Encryption Warning page, read and understand the warning. Make note of the referenced documents to provide to your SQL team. Take advantage of the option to make a backup of the Database Master Key (DMK) by entering a path to a directory on your SQL server along with a filename for the backup file and a password to encrypt the file and clicking Backup. The user running the Keyfactor Command installer must have write permissions to this directory. Click Continue.
Important: Keyfactor Command uses Microsoft SQL Server encryption to protect security sensitive data, including service account credentials. Backup of the SQL server Database Master Key (DMK) is of critical importance in database backup and recovery operations. The backup file of the DMK and the password should be stored in a safe, well-documented location. Without the file and password created with this process, some data that is encrypted within the Keyfactor Command database will be unrecoverable in a disaster recovery scenario.If you choose to install Keyfactor Command in the default location, the referenced documents can later be found here:
C:\Program Files\Keyfactor\Keyfactor Platform\Configuration\DMKBackup.docxC:\Program Files\Keyfactor\Keyfactor Platform\Configuration\DMKRestore.docx
Figure 538: Configure: Backup Database Master Key
-
On the Keyfactor Command License upload page, click Upload and browse to locate the license file provided to you by Keyfactor. This file should have the extension CMSLICENSE. Once the uploaded license shows as valid, click Continue.
Figure 539: Configure: Upload License
-
In the Keyfactor Command configuration wizard, you can choose to upload a configuration file to populate the fields. You may have a file saved from a previous run of the configuration wizard or you may be provided one by Keyfactor. To upload a file, in the configuration wizard, click File at the top of the wizard and choose Open Data File. Browse to locate the configuration file. Configuration files have an extension of .cmscfg. The file may be protected with a password. If it is, you will need to provide this password to open the file. Continue with the remainder of the steps, reviewing the tabs to assure that the data is complete and correct.
Note: If you open a configuration file that contains configuration information for an identity provider other than Active Directory but does not set OAuth enabled to true, the additional identity provider information will not be loaded.
Figure 540: Configure: Open Data File
Note: At the bottom of the configuration wizard, if the database server name is longer than will fit in the provided window, it will be truncated and an ellipsis will be added. - Configure the tabs of the configuration wizard as follows.
-
KeyfactorAgents (Keyfactor Command agent and orchestrator
Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. service endpoint An endpoint is a URL that enables the API to gain access to resources on a server.) -
KeyfactorAnalysis (Keyfactor Command dashboard and reporting)
-
KeyfactorProxy (Authentication for an identity provider other than Active Directory)
-
KeyfactorPortal (Keyfactor Command Management Portal)
That the discovery document is reachable using the Authority value provided and can be parsed into a valid discovery document.
That the Authority URL matches the Issuer returned in the discovery document.
That all the URLs on the discovery document are using HTTPS.
That the JSONWebKeySetUri value is included on the discovery document.
That any endpoint configuration values (Authorization Endpoint, Token Endpoint, UserInfo Endpoint, JSONWebKeySetUri) that have been saved or are being saved match—including case—the values returned in the discovery document. The UserInfo Endpoint is not a required configuration field, but if a value is provided, it must match what’s in the discovery document.
-
Store the secret information in the Keyfactor secrets table.
A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.
-
Load the secret information from a PAM provider.
See Privileged Access Management (PAM) for more information.
-
If you select Windows Authentication, login(s) will be created in SQL for the application pool user(s) you created on the Application Pools tab and granted appropriate permissions (other than the application pool for the Logi Analytics Platform, which does not need database access).
-
If you choose SQL server authentication, enter a User and Password of a SQL administrator for the Keyfactor Command SQL database. If the user does not exist in SQL, it will be created and granted the necessary permissions for management of the Keyfactor Command database. If the user already exists in SQL, it will be granted the necessary permissions. If the database you originally connected to is an Azure database, SQL Server Authentication is the only option provided.
-
On the Administrative Users tab, click Add to add users or groups that you will use to control administrative access to the Keyfactor Command Management Portal.
Enter only the users and/or group(s) to which you want to grant full administrative rights to the Keyfactor Command Management Portal. Following initial configuration, you can create other permission levels and grant those permission levels to other users or groups through the Keyfactor Command Management Portal.
Users and Groups for Active Directory as an Identity Provider
For each user to be added:
-
In the Identity Provider dropdown, select Active Directory.
-
In the Claim Type dropdown, select ADUser for a user account or ADGroup for a group created in Active Directory.
-
In the Claim Value field enter the user or group name for the account in DOMAIN\name format (e.g. KEYEXAMPLE\Keyfactor Administrators).
-
In the Description field enter a description to help you identify the user or group (e.g. the user’s name).
Important: The built-in Active Directory groups Domain Admins and Enterprise Admins cannot be used directly to grant access to the Management Portal due to how these groups function within Windows. You can create a custom Active Directory group, reference that group in the Management Portal, and add the built-in Domain Admins or Enterprise Admins group to that custom group, if desired.Important: For environments using Active Directory as an identity provider, the administrative group must be created as a Global or Universal group. If the administrative group is created as a domain-local group, it will not be recognized by the Management Portal Security Roles and Identities configuration. Configuration of the Management Portal will be incomplete until the group is deleted and recreated as a Global or Universal group.
Figure 550: Configure: Administrative Users Tab for Active Directory as an Identity Provider
Users for OAuth Identity Providers
For each user to be added:
-
In the Identity Provider dropdown, select the display name of the identity provider you created on the Authentication tab.
Note: Both enabled and disabled identity providers appear in the Identity Provider dropdown. Identity providers added in the configuration wizard are marked as enabled by default. Identity providers cannot be enabled or disabled in the configuration wizard. -
In the Claim Type dropdown, select OAuthSubject for a user account created in your OAuth identity provider, OAuthRole for a role created in your OAuth identity provider, or OAuthClientId for a client application created in your OAuth identity provider. If your claim doesn’t fall into one of these categories, select OAuthOid.
-
In the Claim Value field enter the GUID for the user account, role name for the role, or client ID for the client (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). If you selected OAuthOid, enter an appropriate ID to identify the claim.
-
In the Description field enter a description to help you identify the user (e.g. the user or group name).
Figure 551: Configure: Administrative Users Tab for OAuth as an Identity Provider
-
-
On the Dashboard and Reports tab, enter the FQDN of the server hosting the Keyfactor CommandManagement Portal—where the Logi Analytics Platform is installed—in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor CommandManagement Portal component or a DNS alias pointing to the server. Check or uncheck the Use SSL box as appropriate for your environment. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown.
Note: If you are installing the Management Portal in a load balanced configuration, see Appendix - Logi Load Balancing: Keyfactor Command Configuration Wizard Setup.
Figure 552: Configure: Dashboard and Reports Tab
-
On the Orchestrators tab, enter the FQDN of the server hosting the Keyfactor Command orchestrators web site in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Services (Orchestrator Services API) components or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Reenrollment Section (Optional)
In the Template For Submitted CSRs field, from the dropdown, select the template to be used for reenrollment requests made from the Certificate Stores page.
In the CA For Submitted CSRs field, enter the certificate authority
A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. used for reenrollment requests made from the Certificate Stores page. The CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. should be entered in the format FQDN\Logical Name The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two)..
Figure 553: Configure: Orchestrators Tab
Certificate Authentication Section (Optional)
In the Certificate Authentication section of the Orchestrators tab, check the Enabled box if you wish to support client certificate enrollment from the Keyfactor Universal Orchestrator
The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers.. In the Certificate Authentication HTTP Header field, enter the HTTP header appropriate to your client certificate authentication method (see Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication Directly and Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC. In the Certificate Authentication Username and Certificate Authentication Password fields, enter the credentials for the Active Directory user configured to authenticate the orchestrator(s) to the Keyfactor Command server. -
On the API tab, enter the FQDN of the server hosting the Keyfactor CommandKeyfactor API service in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Services (Keyfactor API) components or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Figure 554: Configure: API Tab
-
On the CA Connector API tab, enter the FQDN of the server hosting the Keyfactor Command CA Connector API service in the Host Name field. This can be either the actual host name of the server on which you are installing the CA Connector API component or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Task Queue Section
In the Task Queue section of the page, enter the following information to provide Keyfactor Command with the necessary information to acquire a token for and then communicate with your instance of RabbitMQ:
-
Task Queue URL
The amqp or amqps URL to the RabbitMQ instance. For example:
amqps://appsrvr12.keyexample.com -
Authentication Type
Select either Username/Password or OAuth Client Credentials. The remaining fields will vary depending on the selection you make here. Keyfactor strongly recommends that if you choose the Username/Password option, you connect to RabbitMQ over a secure channel (amqps).
-
Username/Password Details
If you selected Username/Password, enter a Username and Password valid for authentication to the RabbitMQ instance.
-
OAuth Client Credentials Details
If you selected OAuth Client Credentials, enter the following information:
-
Token URL
Set this to the URL of the token endpoint for your OAuth identity provider. For example:
https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token -
Client ID
The client you created in your OAuth identity provider to authenticate to your RabbitMQ instance. If you’re using Keyfactor Identity Provider, see Service Accounts for help creating a client account.
-
Client Secret
The secret of the client you created in your OAuth identity provider to authenticate to your RabbitMQ instance.
-
Scope
One or more scopes that should be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.
-
Audience
Specify an audience value to be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.
-
Figure 555: Configure: CA Connector API Tab
Tip: While not required for operation, the CA Connector API can use WebSockets as a transport protocol. To leverage WebSockets, it must be installed in IIS. This can be done via Server Manager under Add Roles > Web Server (IIS) > Web Server > Application Development > WebSocket Protocol. If WebSockets are not enabled, HTTP long-polling will be used as the transport protocol. -
-
On the Auditing Configuration tab, enter the number of weeks to retain audit data in the Audit Entry Retention Period (weeks) field. By default, 52 weeks of data is retained.
Note: Configuration wizard files from existing databases will not populate this field upon upgrade to prevent changing the retention period to an potentially unwanted setting. Previous versions of Keyfactor Command set this value in years.The audit log cleanup job runs once daily and removes any audit log entries older than the time specified in the retention parameter
A parameter or argument is a value that is passed into a function in an application. except those in the following protected categories:
-
Security
-
CertificateCollections
-
ApplicationSettings
-
SecurityClaims
-
SecurityRoles
-
IdentityProviders
Linux SysLog Server Section
In the Linux SysLog Server section of the page, check the Connect to SysLog to enable the option to copy audit logs in real time to a separate server for collection
The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). and analysis with a centralized logging solution (e.g. rsyslog Rsyslog is an open-source software utility used on UNIX and Unix-like computer systems for forwarding log messages in an IP network., Splunk, Elastic Stack). In the Host Name field, enter the fully qualified domain name of the server that will be receiving the logs. Set the Port to the port on which your log receipt application is listening to receive the logs. The default value is 514 (the default rsyslog port). If desired, turn on Use TLS SysLogging. When you click Save, Keyfactor Command will verify that a connection can be made to the specified server on the specified port. Additional configuration on both the Keyfactor Command server and log receipt server are needed to make TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. communications work (see Prepare for External Log Shipping over TLS (Optional)). If you have not yet completed these configurations, you will receive a validation error on save if the Use TLS SysLogging option is enabled.Note: Keyfactor Command uses RFC 5424 for syslog messages when using TLS and RFC 3164 when not using TLS.The auditing settings can be updated on the auditing tab of the applications settings page following installation
Figure 556: Configure: Audit Configuration Tab
-
-
At this point in the configuration, if you have populated all the required fields, the yellow warning banner at the top of the configuration wizard should have disappeared. If it is still visible, click the dropdown arrow to open the Warnings page and review the warning(s) to see what needs to be corrected. Under some circumstances you will be allowed to continue with the configuration even if the yellow warning banner is still present. You will know this is the case if the Verify Configuration button is active. Under these circumstances, you should review the warnings before continuing.
Figure 557: Configure: Configuration Warnings
-
Before completing the configuration wizard, you may choose to save a copy of the configuration as a file for future use. To download the configuration as a file, in the configuration wizard, click File at the top of the wizard and choose Save Data File. Browse to a location where you want to save the configuration file, enter a file name and click Save. You will be prompted to enter a password to encrypt the data in the file. You may choose to protect the file with a password or not. If you use a password at this time, you will need to provide this password to open the file. Keyfactor highly recommends using a strong password to protect the file. If you do not wish to use a password to protect the file, sensitive information (e.g. passwords for the service accounts entered in the configuration wizard) will be removed from the file. Once you enter a password or uncheck the encryption box, click OK to save the file.
Important: Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.
Figure 558: Configure: Save Configuration as a File
- At the bottom of the Keyfactor Command Configuration Wizard dialog, click Verify Configuration.
-
On the Configuration Operations page, review the planned operations and then click Apply Configuration. Prior to clicking Apply Configuration, you can revisit any of the Configuration Wizard tabs to review or make changes by clicking Edit Configuration.
Figure 559: Configure: Configuration Operations
-
When the configuration completes successfully, you will see the below message. If you didn’t save a copy of the configuration earlier, you may do so at this time by clicking Save Settings. Otherwise, click Close to close the dialog.
Figure 560: Configure: Configuration Complete
Application Pools Tab
A separate application pool is required for each virtual directory that will be created for Keyfactor Command in IIS. If you’ve chosen to install all the Keyfactor Command components, this will be five application pools for the virtual directories with the following names, by default:
On the Application Pools tab of the configuration wizard, click Add, change the default application pool name, if desired, and enter the user name (DOMAIN\username format) and password of the Active Directory service account under which the application pool will run. You may use the people picker button (
) to browse for the account. Click the verify button (
) to confirm that the username and password entered are valid. Assuming the verification completes successfully, click Save.
Figure 541: Configure: Application Pools
Authentication Tab
On the Authentication tab of the configuration wizard, check the Use OAuth for Keyfactor Portal, API, and Orchestrators box if you wish to use one or more OAuth identity providers as either a direct identity provider or a federation gateway to another identity provider. If you do not select this, you will be using the default identity provider of Microsoft Active Directory. If you checked OAuth, configure it as follows. If you opted to install the CA Connector API component, the Use OAuth for CA Connector API box will be shown checked and grayed out. This box cannot be unchecked. OAuth authentication is required for the CA Connector API. If either OAuth box is checked, configure OAuth as follows. If only the Use OAuth for CA Connector API box is checked, the remainder if the top section, the Claims Proxy section, and the Identity Provider Token Credentials section will be grayed out. Skip to the Identity Provider section for configuration.
On the Authentication tab in the top section, accept the defaults for the Session Expiration and Cookie Expiration or modify these if appropriate for your environment. The Session Expiration value determines the length of time a Keyfactor Command browser session in the Management Portal will remain logged in before the user is prompted to re-authenticate regardless of whether the session is idle or in active use. The Cookie Expiration value determines the length of time the authentication cookie
Select an OAuth identity provider in the Default Login dropdown. This dropdown will only be populated once you add at least one identity provider in the identity providers section and enter values in the provider’s Authentication Scheme (reference name) and Display Name fields. The default login applies to users attempting to access Keyfactor Command who do not provide an Identity Provider Hint in the request URL to be directed to a specific identity provider for authentication. If you have only one identity provider, set the default login to this identity provider. If you have multiple identity providers, you may wish to set the default login to the most heavily used identity provider and provide users of other identity providers a URL complete with identity provider hint.
Where keyfactor.keyexample.com is the fully qualified domain name of the Keyfactor Command server, KeyfactorPortal is the virtual directory for the Management Portal on that server, and Command-OIDC-3 is the authentication scheme for the identity provider to use for authentication.
Claims Proxy Section
On the Authentication tab in the Claims Proxy section, enter the FQDN that you will use to access the Keyfactor CommandManagement Portal in the Host Name field. This can be either the actual host name The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). of the server on which you are installing the Keyfactor Command Administration component or a DNS The Domain Name System is a service that translates names into IP addresses. alias pointing to the server. If you have multiple Keyfactor Command Management Portal servers with load balancing, this will be a DNS name pointing to your load balancer. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown.
Figure 542: Configure: Identity Providers—OAuth Claims Proxy Section
Identity Provider Section
On the Authentication tab in the Identity Provider section, click Add to create a new identity provider. You may create more than one OAuth identity provider, any of which may be used to authenticate to Keyfactor Command (so users from OAuth IdP A and users from OAuth IdP B may both access Keyfactor Command). Active Directory may not be configured in conjunction with any OAuth identity providers and you may use only one Active Directory identity provider. Select the identity provider currently being edited in the Identity Provider dropdown.
In the Identity Provider Parameters section, enter an Authentication Scheme (reference name) and replace the default Display Name, if desired, for the identity provider being added. The Authentication Scheme should be entered without spaces. This is used in constructing URLs that reference the identity provider from Keyfactor Command. In the Type dropdown, select an appropriate type for your identity provider. Most identity providers can be supported with the Generic type. For Auth0, select the Auth0 type.
For Keyfactor Identity Provider, the Authentication Scheme you enter here must match the name you used when configuring the redirect URLs for Keyfactor Identity Provider (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).
Populate the identity provider parameters according to Table 899: Identity Provider Parameters. The fields that appear will vary depending on the selected Type. HTTPS is required for URL parameters. For more information about identity providers, see Selecting an Identity Provider for Keyfactor Command.
Figure 543: Configure: Identity Providers—OAuth Identity Provider Section for Type Generic
Table 899: Identity Provider Parameters
| Name | Type | Example |
Description |
|---|---|---|---|
|
|
1 - String | Command- OIDC- Client |
The audience value for the identity provider. For Keyfactor Identity Provider, this should be set to the same value as the Client Id. For example: Command- OIDC- Client
This parameter is required. |
|
|
1 - String |
The unique identifier defined in Auth0 or a similar identity provider for the API. This parameter only appears if Auth0 is selected as the type and is required in that case. |
|
| Authority | 1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor |
The issuer/authority endpoint URL for the identity provider. For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. This parameter is required. Tip: When you add or update an identity provider, the provider’s discovery document is validated based on this authority URL. The discovery document is also validated periodically in the background. The following are validated:
If any of these validation tests fail, any identity provider changes in process will not be saved and an error will be displayed or logged. |
|
|
1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /auth |
The authorization endpoint URL for the identity provider. For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. This parameter is required. |
|
|
1 - String | Command- OIDC- Client |
The ID of the client application created in the identity provider for primary application use. For Keyfactor Identity Provider, this should be: Command- OIDC- Client
For more information, see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). This parameter is required. |
|
|
2 - Secret |
The secret for the client application created in the identity provider for primary application use. For Keyfactor Identity Provider, see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation for help locating this. It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. Supported methods to store secret information are: This parameter is required. |
|
|
|
1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor /.well-known /openid-configuration |
The discovery URL for the identity provider. For Keyfactor Identity Provider, this is the link to the OpenID Endpoint Configuration page, which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). Populate this value and click Fetch to populate the remainder of the fields in this section, if desired. If you opt not to populate this field or if the discovery document does not return a valid response, the remainder of the fields in this section of the configuration will need to be configured manually. This value is not stored in the database. This field does not appear in the Management Portal identity provider configuration. |
|
|
1 - String | cid |
A type of user claim for the identity provider containing a backup unique name for the user. This is provided in case the primary referenced name (see cid
The cid (client ID) user claim type is also commonly used by other OAuth providers. This parameter is required. |
|
|
1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs |
The JWKS (JSON Web Key Set) URL for the identity provider. For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. This parameter is required. |
| 1 - String | preferred_ username |
A type of user claim for the identity provider containing a friendly name for the user. Although the value for this field may not necessarily be unique within your identity provider (so might resolve to John Smith and the organization might have two users called John Smith), this can be confusing in Keyfactor Command, since the value is used as the user’s display name in areas such as the requester of a certificate, actors in audit logs, and users referenced in workflow instances. It is best to avoid duplicates. For Keyfactor Identity Provider, this should be: preferred_ username
For Okta, this might be preferred_names (e.g. john.smith@keyexample.com) or just name (e.g. John Smith). For Auth0 this might be name (e.g. johnsmith@keyexample.com). This parameter is required. Tip: The value in this field is used as the first choice to populate the username in the Keyfactor Command Management Portal header, if available. This is not the value to use when logging into Keyfactor Command. For that, see
|
|
| 1 - String | groups |
The value used to reference the type of group claim for the identity provider. For Keyfactor Identity Provider, this should be: groups
This parameter is required. |
|
|
|
1 - String |
One or more scopes that are requested during the OIDC protocol when Keyfactor Command is the relying party. Multiple scopes should be separated by spaces. This value is not used for Keyfactor Identity Provider. |
|
|
|
1 -String | https:// my-auth0-instance .us.auth0.com /oidc/logout |
The signout URL for the identity provider. This parameter only appears if Auth0 is selected as the type and is required in that case. |
| Timeout | 1 - String | 60 | The number of seconds a request to the identity provider is allowed to process before timing out with an error. |
|
|
1 - String |
An audience value to be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client. This value is not used for Keyfactor Identity Provider. |
|
|
|
1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /token |
The token endpoint URL for the identity provider. For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. This parameter is required. |
|
|
1 - String |
One or more scopes that should be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client. Multiple scopes should be separated by spaces. This value is not used for Keyfactor Identity Provider. |
|
|
|
1 - String | sub | A type of user claim for the identity provider containing a unique name for the user. For Keyfactor Identity Provider, this should be: sub In Keyfactor Identity Provider, this is a GUID uniquely identifying the user. The sub (subject) user claim type is also commonly used by other OAuth providers. See also This parameter is required. Tip: The value in this field is used as the second choice to populate the username in the Keyfactor Command Management Portal header if the The value in this field is the one to use when logging into Keyfactor Command. |
|
|
1 - String | https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs |
The user info endpoint URL for the identity provider. For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct. |
Identity Provider Token Credentials Section
On the Authentication tab in the Identity Provider Token Credentials section, enter a Client Id and Client Secret for a service account you have created in one of your identity providers to allow Keyfactor Command to make API requests to itself. Select the appropriate identity provider for the account in the Identity Provider Name dropdown. This does no need to be the default identity provider. These values are required. Enter values in the Token Audience and Token Scope fields if necessary for your identity provider. These fields are not used for Keyfactor Identity Provider.
For Keyfactor Identity Provider, this is created as a client (see Service Accounts). Keyfactor recommends that you use a different client for this purpose than the client used for the main connection from Keyfactor Command to the identity provider (see Client Id in Table 899: Identity Provider Parameters).
Figure 544: Configure: Identity Providers—OAuth Identity Provider Token Credentials Section
Database Tab
On the Database tab in the top section, select an Authentication Mode for ongoing communications to SQL server—Windows Authentication or SQL Server Authentications. Your SQL server must be configured to support mixed mode authentication in order to use the SQL server authentication option.
For more information, see Grant Permissions in SQL.
Encryption Section
If desired, check the Configure Encryption box. This option allows you to encrypt select sensitive data stored in the Keyfactor Command database using a separate encryption methodology utilizing a Keyfactor Command-defined certificate on top of the SQL server encryption noted above. This additional layer of encryption protects the data in cases where the SQL Server master keys cannot be adequately protected. Read and understand the encryption warning. This warning applies to implementations with more than one Keyfactor Command server.
Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure..Select Application and SQL for the Encryption Type and click the Select button to choose a certificate from the Personal Certificate store of the Local Computer with which to encrypt the data. Only valid certificates with the appropriate key usage will appear in the selection dialog. See Acquire a Public Key Certificate for the Keyfactor Command Server.
If you enable application-level encryption, your certificate must either be using a key storage provider (KSP) or you must manually grant permissions to the certificate’s private key (see Application-Level Encryption).
Figure 545: Configure: Encryption Warning
Figure 546: Configure: Database Tab
Service Tab
On the Service tab, enter the user name and password of the Active Directory (DOMAIN\username format) or local (HOSTNAME The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername).\username format) service account under which the Keyfactor Command Service will run. This can be the same service account used for the application pool(s) or a different service account. You may use the people picker button () to browse for the account. Click the verify button () to confirm that the username and password entered are valid. If desired, check the Start service on bootup box to start the Keyfactor Command Service at system start.
Email Tab
On the Email tab, enter the FQDN of your SMTP Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. server, the SMTP port (default is 25), and the sender name and account. Depending on the email configuration in your environment, the sender account may need to be a valid user on your mail server (using Active Directory credentials) or you may be able to put anything in this field (if your mail server supports anonymous connections). You may use the people picker button () to browse for the sender account if you are using a valid account. Select the Use SSL box if this option is supported by your mail server and select the appropriate authentication method for your environment. If your mail server requires that you provide a username and password for a valid user, enter that Active Directory username and password in the fields at the bottom of the page after selecting the Explicit credentials radio button. You may use the people picker button () to browse for the account. Click the verify button () to confirm that the username and password entered are valid. The user you select here must match the email address you set in the Sender Account field if you select Explicit credentials. The information entered on this tab may later be changed in the Keyfactor CommandManagement Portal.
Figure 548: Configure: Email Tab
Keyfactor Portal Tab
On the Keyfactor Portal tab in the top section, enter the FQDN that you will use to access the Keyfactor Command Management Portal in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Administration component or a DNS alias pointing to the server. If you have multiple Keyfactor Command Management Portal servers with load balancing, this will be a DNS name pointing to your load balancer. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Enrollment Section
In the Enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). section of the page, modify the default Certificate Subject Format field, if desired. The subject values provided in this field are substituted at processing time for any entered by the user in PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. enrollment or provided with enrollment defaults if the template used is set to supply in request.
The data in the subject format takes precedence over any data entered during PFX enrollment or supplied by enrollment defaults
The organization for certificates generated through PFX enrollment will always be Key Example, Inc. regardless of what is shown on the PFX enrollment page during enrollment.
This setting also applies to CSRs generated using the CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. generation method.
Data from the default subject does not display in the PFX enrollment form. To define defaults that will display in the PFX enrollment form (and can be modified by users), use enrollment defaults
PFX Enrollment Section
In the PFX Enrollment section of the page, select the Domain radio button if you wish PFX files to be protected with the user’s Active Directory password or select the Auto-Generated radio button if you wish PFX files to be protected with a one-time password. Check the Alphanumeric Password Characters box if you wish the one-time password used to protect PFX files to contain numbers and letters. Uncheck the Alphanumeric Password Characters box if you wish the one-time password used to protect PFX files to contain numbers, letters and special characters. In the Password Length field, enter a number for the number of characters the one-time password should have. The minimum value is 8. If you select the Domain radio button, the data entered in the password fields is not relevant.
Figure 549: Configure: Keyfactor Portal Tab
Administrative Users Tab
Dashboard and Reports Tab
Orchestrators Tab
API Tab
CA Connector API Tab
Audit Configuration Tab